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The Pixel Bar API is a set of C style functions that enable the xSides application to define 
pixel bars and display device dependent bitmaps in the pixel bars. The API includes functions 
to initialize the interface, create, modify, query and delete pixel bars, and to display colors or 
bitmaps in the pixel bars. For Win32 implementations, the API functions exist in a 
dynamically linked library (DLL). 



The API functions include: 



• Pixelbarjtoit initializes and configures the API and the Pixel Bar software. 
The API functions are enabled 



• Pixelbar_Uninit restores the API and the Pixel Bar software to default 
undefined state. Other than Pixelbarjnit, all API functions are disabled. 

• PixeIbar_Create creates a pixel bar and specifies its characteristics ~ 
location, size, and whether it's visible or not. Also specifies the mode to 
use to acquire the screen area. 

• Pixelbar_CreateMR creates a pixel bar and specifies its characteristics 
location, size, and whether it's visible or not for each supported display 
resolution. Hie mode used to acquire the screen area is also specified. This 
function differs from Pixelbar_Create in that when the display resolution 
changes, the xSides Space is automatically resized without further input 
from the xSides application. 

• PixeIbar_Modify modifies the state of an existing pixel bar. 

• PixelbarJ)elete deletes an existing pixel bar. The screen area is reclaimed, 
and the pixel bar is no longer displayed. 

• Pixelbar_Activate makes a pixel bar, active and visible on the screen. 

• Pixelbar ^Deactivate makes a pixel bar inactive and no longer visible on 
the screen. The screen area formerly occupied by the pixel bar is reclaimed. 

• PixeIbar_Query returns the current state of the specified pixel bar, 
including location, size, visibility, etc. 

• Pixelbar_Enumerate returns the number of pixel bars and their state. 

• Pixelbar_SetMouseEvent sets a mouse event that will be reported to the 
application via a callback function. 
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Pixelbar_ClearMouse£vent deletes the specified mouse event The 
application will no longer receive reports for the mouse event. 

Pixelbar_EnumerateMouseEvents returns the list of current mouse events 
that the pixel bar software reports. 

Pixelbar_QueryMouseEvent returns the information of a specific mouse 
event the pixel bar software services. 

PixelbarEnableMouse enables the display of the mouse cursor icon in a 
pixel bar, 

PixelbarDisableMouse disables the display of the mouse cursor icon in a 
pixel bar. 

Pixelbar_QueryDispIayInfo returns the current physical screen resolution 
and other display information (e.g. refresh rate). The physical screen 
resolution doesn't include the screen areas occupied by pixel bars in 
overscan mode. 

PixelbarJDisplayColor displays a color across the entire specified pixel 



PixelbarJDisplayBitmap displays a device dependent bitmap (i.e. a bitmap 
in the current screen format) at the specified location in the specified pixel 
bar. 

PixelbarJSetDispIayEvent sets a display event that will be reported back 
to the application via a callback function. 



H fl • Pixelbar_ClearDisplayEvent deletes the specified display event 

I y • PixelbarEnumerateDisplayEvents returns the list of display events that 

f y are currently set 

C3 

?S • Pixelbar_QuerySupport returns the capabilities of the virtual xSides 

device. 

• Pixelbar_EnumerateFilelnformation returns the list of xSides driver files, 
their locations, names and versions. 



A number of data structure types are used by the Pixel Bar API. They include: 

• PBConfiguration describes the configuration of the pixel bar software for 
the current run. 

• PBPixelBarState describes the current state of a pixel bar. 

• PBDisplayState describes the current state of a display. 

• CURSOR_POS contains the x and y coordinates of the cursor. 
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• PBMouseEvent contains the information that is passed back to the 
application's mouse event callback function in response to a mouse event 

• PBMouseEventlnfo describes the current state of a mouse event set. 

• PBDisplayEvent contains the information that is passed back to the 
application in response to a display event. 



Pixelbarjnit 

UINT32 Pixelbarjnit (PBConfiguration *lpPBConfiguration) 

Initializes the pixel bar software and configures it using the data in the PBConfiguration 
parameter. 

• Returns one of these values: 

PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

Parameters 

LpPBConfiguration 



I* Pointer to the configuration data structure. The pixel bar software is configured 

for the current session by the values in this data structure. 

ru 

ifj Notes 

Q 

C3 None. 

PixelbarJJninit 

UINT32 Pixelbar JJninit(void) 

Uninitializes the pixel bar software restores it to the uninitialized state. All resources 
allocated and used by the pixel bar software during an xSides session is freed. 

• Returns one of these values: 

PB_SUCCESS Function was successful. 

PBJ3RROR An unrecoverable error occurred. 

Parameters 

This function has no parameters. 
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Notes 

None. 



Pixelbar_Create 



UINT32 Pixelbar_Create (UINT32 *lpPixeIbarId, UINT32 xSidesMode, 
UINT32 Flags, UINT32 Displayld, UINT32 Edge, INT32 
OriginX, INT32 OriginY, UINT32 Width, UINT32 Height) 

Pixelbar_Create0 creates a pixel bar and returns the id. Memory is allocated for the pixel bar 
and, if created with the active flag, screen space is created on the display surface. 

• Returns one of these values: 

PBJSUCCESS Function was successful. 

£3 PB_ERROR An unrecoverable error occurred. 

\Q 

^■j Parameters 

CD IpPixelbarld 

ru 

A pointer to the pixel bar id returned by Pixelbar_Create(). 
xSidesMode 

H : The xSides mode that the pixel bar is to operate in. May be one of the 

*"* following: 

ru 

CO • MODE_SHARE Share mode -- shares the current 

□ display resolution with the desktop by decreasing the desktop size. 

• MODE_STEPUP Step Up mode - increases the 
physical resolution of the display, but keep the desktop at the current 
resolution and use the difference for displaying the pixel bar. 

• MODE STEPDOWN Step Down mode maintains the 
physical resolution of the display, but force the desktop to the next smaller 
defined resolution and use the difference for displaying the pixel bar. 

• MODE_OVERSCAN Overscan mode - reprograms the 
video hardware to provide extra scanlines at the bottom of the screen to 
display the pixel bar. This mode currently is valid only for pixel bars at 
the bottom or top edge of the display. 

• MODE_AUTO Automatic mode -- the pixel bar software 
will attempt to use Overscan mode first, and if thafs not possible, then use 
Share mode, 



Flags 
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Flags specifies the options and features of the Pixelbar_CreateO function and of 
the pixel bar that is created. 

The options are specified by the following bitfields; 

• PB_FLAGS_ACnVE: Can be TRUE (1) or FALSE (0), which 
specify, respectively, whether the pixel bar is active or inactive upon 
creation. Active pixel bars are visible while inactive pixel bars are not 
visible, but may still be operated upon and updated. 

• PB_FLAGS_EXACT_SIZE: Can be either TRUE (1) or FALSE 
(0), which specify respectively whether the pixel bar should be created 
with the exact size specified, returning an error if it's not possible, or 
with the closest size possible if there are not sufficient resources to 
provide the specified size. If the application creates the pixel bar with 
the PB_STATUS_EXACTJSIZE set to FALSE, it should query for the 

e actual size created with Pixelbar_QueryO function. 
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FLAGS. 


INVALID: What is this? 


• 


PB. 


FLAGS, 


VALIDRES: What is this? 


• 


PB. 


FLAGS. 


MOUSE_ENABLED: What is this? 


• 


PB 


FLAGS 


DISPLAYED: What is this? 
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Displayld specifies the display surface (aka monitor, screen) that the pixel bar 
will be displayed on. This feature supports multiple monitor systems. 
Currently, only Displayld of 0 is supported. 



Edge 



rg Edge specifies which edge of the display surface the pixel bar will be displayed 

on. May be one of the following: 



4c* 



PBJTOPJEDGE The top edge. 

PB_BOTTOMJ£DGE The bottom edge. 

PB_RIGHT_EDGE The right edge. This edge 
is not valid if the pixel bar is in Overscan mode. 

PB_LEFTJEDGE The left edge. This edge 

is not valid if the pixel bar is in Overscan mode. 



OriginX 



OriginX specifies the x position on the display surface, in units of pixels with 
respect to the Desktop Origin, where the origin of the pixel bar (which is the 
upper left corner of the pixel bar) is located The pixel bar origin must be 
consistent with its screen edge parameter; otherwise an error will be returned. 
This is a signed value and may be a negative value (which it will be for non-zero 
width pixel bars on the left edge of the screen.) 
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OriginY 

OriginY specifies the y position on the display surface, in units of pixels with 
respect to the Desktop Origin, where the origin of the pixel bar (which is the 
upper left corner of the pixel bar) is located The pixel bar origin must be 
consistent with its screen edge parameter, otherwise an error will be returned. 
This is a signed value and may be a negative value (which it will be for non-zero 
height pixel bars on the top edge of the screen.) 

Width 

Width specifies the desired width of the pixel bar, in number of pixels. It may 
not be larger than the total physical horizontal resolution of the display, which 
include the desktop and the pixel bars. 

Height 

Width specifies the desired height of the pixel bar, in number of pixels. It may 
not be larger thain the total physical vertical resolution of the display, which 
include the desktop and the pixel bars. 

Notes 

The interaction of pixel bars running in different xSides modes is currently 
undefined, and therefore not supported. Hence, in a session, all pixel bars must 
be in the same xSides mode. 

Pixelbar_CreateMR 

UINT32 Pixelbar_CreateMR(UINT32 *lpPixeIbarId, UINT32 

xSidesMode, UINT32 Flags, UINT32 Displayld, UINT32 
Edge, PBPixelbarSize *IpPixelbarSize, UINT32 
xSidesResolutionCount) 

Pixelbar_CreateMRO creates a pixel bar and returns the id. This functions replaces 
Pixelbar_Create() and allows pixel bar sizes for various resolutions to be specified. This 
function differs from PixeIbar_Create in that when the display resolution changes, the xSides 
Space is automatically resized without further input from the xSides application. 

• Returns one of these values: 

PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

Parameters 

IpPixelbarld 

A pointer to the pixel bar id returned by Pixelbar_CreateMR(). 
xSidesMode 
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The xSides mode that the pixel bar is to operate in. May be one of the 
following: 



• MODEJJHARE Share mode -shares the current 
display resolution with the desktop by decreasing the desktop size. 

• MODE.STEPUP Step Up mode -increases the 
physical resolution of the display, but keep the desktop at the current 
resolution and use the difference for displaying the pixel bar. 

• MODE_STEPDOWN Step Down mode maintains the 
physical resolution of the display, but force the desktop to the next smaller 
defined resolution and use the difference for displaying the pixel bar. 

• MODE_OVERSCAN Overscan mode — reprograms the 
video hardware to provide extra scanlines at the bottom of the screen to 
display the pixel bar. ITus mode currently is valid only for pixel bars at 
the bottom or top edge of the display. 



Flags 



MODE_AUTO Automatic mode — the pixel bar software 

will attempt to use Overscan mode first, and if that's not possible, then use 
Share mode, 



Flags specifies the options and features of the Pixelbar_Create() function and of 
p.\ the pixel bar that is created. 



The options are specified by the following bitfields: 

• PB_FLAGS_ACTTVE: Can be TRUE (1) or FALSE (0), which 
specify, respectively, whether the pixel bar is active or inactive upon 
if creation. Active pixel bars are visible while inactive pixel bars are not 

fU visible, but may still be operated upon and updated. 

^— 

C3 • PB_FLAGS_EXACT_SIZE: Can be either TRUE (1) or FALSE 

Q (0), which specify respectively whether the pixel bar should be created 

with the exact size specified, returning an error if it's not possible, or 
with the closest size possible if there are not sufficient resources to 
provide the specified size. If the application creates the pixel bar with 
the PB_STATUS_EXACT_SIZE set to FALSE, it should query for the 
actual size created with Pixelbar^QueryQ function. 



PB_FLAGS_INVALED : What is this? 



• PB_FLAGS_VALEDJtES: What is this? 

• PB_FLAGS_MOUSE_ENABLED: What is this? 

• PB_FLAGS_DISPLAYED: What is this? 
Displayld 
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Displayld specifies the display surface (aka monitor, screen) that the pixel bar 
will be displayed on. This feature supports multiple monitor systems. 
Currently, only Displayld of 0 is supported. 



Edge 



Edge specifies which edge of the display surface the pixel bar will be displayed 
on. May be one of the following: 



PB_TOP_EDGE 

PB_BOTTOM_EDGE 

PB_RIGHT_EDGE 

PB LEFT EDGE 



The top edge. 
The bottom edge. 

Hie right edge. This edge is not valid if the pixel bar 
is in Overscan mode. 

The left edge. This edge is not valid if the pixel bar 
is in Overscan mode. 



n 



IpPixelbarSize 



v3 lpPixelbarState is a pointer to an array of pixel bar size and origin data for 

' 4 various screen resolutions. The number of entries in the array is specified by 

fU xSidesResolutionCount. 



xSidesResolutionCount 

xSidesResolutionCount indicates the number of xSides resolutions that are listed 
by IpPixelbarSize. 



FU Notes 



The interaction of pixel bars nmning in different xSides modes is currently 
undefined, and therefore not supported. Hence, in a session, all pixel bars must 
be in the same xSides mode. 



PixelbarJModify 



UINT32 PixelbarJModify (UINT32 Pixelbarld, UINT32 Flags, INT32 
OriginX, INT32 OriginY, UINT32 Width, UINT32 Height) 

Pixelbar_ModifyO modifies the size and position of an existing pixel bar. The xSides mode 
and the edge are not affected. 

• Returns one of these values: 
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PB_SUCCESS Function was successful. 

PBERROR An unrecoverable error occurred. 

Parameters 



Pixelbarld 



The id of the pixel bar. 
Status 

Status specifies the options and features of the Pixelbar_Modify() function and 
of the pixel bar. 



The options are specified by the following bitfields: 

PB_STATUS_ACTIVE: Can be TRUE (1) or FALSE (0), which specify, 

respectively, whether the pixel bar is active or inactive upon creation. 
Active pixel bars are visible while inactive pixel bars are not visible, 
but may still be operated upon and updated. 

^ PB_STATOS_EXACT_SIZE: Can be either TRUE (1) or FALSE (0), 

which specify respectively whether the pixel bar should be created with 

^ the exact size specified, returning an error if it's not possible, or with 

I U the closest size possible if there are not sufficient resources to provide 

f R the specified size. If the application creates the pixel bar with the 

fU PB JSTATUS JBXACTSIZE set to FALSE, it should query for the 

ffj actual size created with Pixelbar_Query() function. 

U 

' OriginX 

f ™ OriginX specifies the x position on the display surface, in units of pixels with 

respect to the Desktop Origin, where the origin of the pixel bar (which is the 

* « upper left corner of the pixel bar) is located The pixel bar origin must be 

v-=f consistent with its screen edge parameter, otherwise an error will be returned, 

f 3 This is a signed value and may be a negative value (which it will be for non-zero 

Q width pixel bars on the left edge of the screen.) 

OriginY 



OriginY specifies the y position on the display surface, in units of pixels with 
respect to the Desktop Origin, where the origin of the pixel bar (which is the 
upper left corner of the pixel bar) is located The pixel bar origin must be 
consistent with its screen edge parameter; otherwise an error will be returned. 
This is a signed value and may be a negative value (which it will be for non-zero 
height pixel bars on the top edge of the screen.) 

Width 



Width specifies the desired width of the pixel bar, in number of pixels. It may 
not be larger than the total physical horizontal resolution of the display, which 
include the desktop and the pixel bars. 

Height 
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Width specifies the desired height of the pixel bar, in number of pixels. It may 
not be larger than the total physical vertical resolution of the display, which 
include the desktop and the pixel bars. 

Notes 



Pixelbar_Modify is currently not supported As currently defined, it is unable to 
modify the origins and sizes of pixel bars created with the Pixelbar_CreateMR() 
function. Pixelbar_Modify potentially may be removed or redefined. 



Pixelbar_Delete 

UINT32 Pixelbar_DeIete (UINT32 Pixelbarld) 

Pixelbar_Delete() deletes an existing pixel bar and frees its resources. 
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• Returns one of these values: 

PB_SUCCESS 

PBJERROR 
Parameters 

Pixelbarld 

The id of the pixel bar. 
Notes 

None. 

Pixelbar Activate 



Function was successful. 

An unrecoverable error occurred. 



UINT32 Pixelbar_Activate (UINT32 Pixelbarld) 

Pixelbar_Activate() activates an existing pixel bar and makes it visible. If the pixel bar uses 
MODE_SHARE, the desktop is reduced and space on the display surface is created for the 
pixel bar. . If the pixel bar uses MODEJDVERSCAN, the video hardware is reprogrammed 
to create the scan lines used by the pixel bar 



Returns one of these values: 

PB_SUCCESS 

PB ERROR 



Function was successful. 

An unrecoverable error occurred. 
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Parameters 

Pixelbarld 

The id of the pixel bar. 
Notes 

None. 

Pixelbar_Deactivate 

UINT32 Pixelbar_Deactivate (UINT32 Pixelbarld) 

PkelbarJDeactivateO deactivates an existing pixel bar and makes it no longer visible. If the 
pixel bar uses MODE_SHARE, then the screen space is returned to the desktop. If the pixel 
bar uses MODE_OVERSCAN, the video hardware is reprograrnmed to remove the scan lines 
used by the pixel bar. 

• Returns one of these values: 
\j PB_SUCCESS Function was successful, 

r fj PB_ERROR An unrecoverable error occurred 

^ : : 

IU 

-ri Parameters 

v ; « 

** Pixelbarld 

T 

X £ 

F The id of the pixel bar. 

I'r Notes 

The behavior Pixelbar_Deativate() if the pixel bar uses MODE_STEPUP or 
MODE_STEPDOWN is currently neither defined nor 
supported.Pixelbar_Enumerate 
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UINT32 PixelbarJEnumerate (UINT32 *lpPixe!barCount, UINT32 
**lpPixelbarIdTab!e, UINT32 *lpPixelbarsReturned, UINT32 *IpszData, 
UINT32 szOutputBuffer) 

Pixelbar_EnumerateO returns the count of existing pixel bars and their ids. The application 
can then get the characteristics of the individual pixel bars by calling Pixelbar_Query(). 

• Returns one of these values: 

PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 
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PB_BUFFER_TOO_SMALL The provided output buffer is too 

small to contain all the requested 
information. The information 
returned in the output buffer is not 
guaranteed to be coherent or valid. 
The function should be called again 
with an output buffer of the 
appropriate size. 



Parameters 

IpPixelbarCount 

lpPixelbarCount is the address of an UINT32 where the count of existing pixels 
will be returned. 

IpPixelbarldTable 

lpPixelbarldTable is the address of an array of pixel bar ids where the existing 
pixel bar ids will be returned. 

IpPixelbarsReturned 

IpPixelbarsReturned is the address of an UINT32 where the count of pixels 
whose ids are returned in IpPixelbarldTable will be written. Unless the output 
buffer pointed to by IpPixelbarldTable is too small; the value in 
IpPixelbarsReturned is the same as in IpPixelbarCount. 

IpszData 

The address of the size of the requested data. If the value is larger than 
szOutputBuffer, then the provided buffer is too small, and the error code 
PBJ3UFFER_TOO_SMALL is returned by the function. 

szOutputBuffer 

The size of the output buffer pointed to by lpPixelbarldtable, in bytes. This will 
allow the Pixel Bar software to refrain from overflowing the buffer. 

Notes 

None. 

Pixelbar_Query 

UINT32 Pixelbar_Query (UINT32 Pixelbarld, PBPixelbarState 
*lpPBState, UINT32 *lpszData, UINT32 szOutputBuffer) 

Pixelbar_Query() returns the state and characteristics of the specified pixel bar, including 
whether it is active, its width and height, etc. 

• Returns one of these values: 
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PB SUCCESS 



Function was successful. 



PB ERROR 



An unrecoverable error occurred. 



PB BUFFER TOO SMALL 



The provided output buffer is too 
small to contain all trie requested 
information. The information 



returned in the output buffer is not 
guaranteed to be coherent or valid. 
The function should be called again 
with an output buffer of the 



appropriate size. 
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Parameters 

Pixelbarjd 

The id of the pixel bar. 
IpPBState 

The address of a PBPixeibarState structure that the pixel bar state is returned in. 



The address of the size of the requested data. If the value is larger than 
szOutputBuffer, then the provided buffer is too small, and the error code 
PB_BUFFER_TOO_SMALL is returned by the function. 

szOutputBuffer 

The size of the output buffer pointed to by IpPBState, in bytes. This will allow 
the Pixel Bar software to refrain from overflowing the buffer. 



Pixelbar_SetMouseEvent 

UINT32 Pixelbar JSetMouseEvent (UINT32 Pixelbarld, UINT32 
*lpMouseEventId, UINT32 MouseEvent, UINT32 
(*fpCalIback)(PBMouseEvent *IpParam)) 



Pixelbar_SetMouseEvent provides the application with a method to be notified of mouse 

events. Multiple mouse events can be requested with a single call to 

Pixelbar SetMouseEvent; an Identifier is returned for each request When multiple requests 



None. 
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specify the same mouse events (e.g. PB_MOUSE_MOVEMENT), all requests are serviced in 
the TBD \possibly reverse] order that they were requested. The notification is performed via 
function callbacks. 



ru 



5U 



Function was successful. 

An unrecoverable error occurred. 



• Returns one of these values: 

PB_SUCCESS 

PB_ERROR 
Parameters 

Pixelbarjd 

The id of the pixel bar. 
IpMouseEventld 

The address of a UINT32 that in which the Pixel Bar software returns the Mouse 
Event Id. 

MouseEvent 

The mouse event that triggers the callback function. It may be one or more of 
the following: 



PBJrfOUSEJLBUTTONJDOWN 



PB_MOUSE_LBUTTON_UP 



PB_MOUSE_RBUTTON_DOWN 



PB MOUSE RBUTTONJJP 



PB_MOUSE_MBUTTON_DOWN 



PB_MOUSE_MBUTTONJJP 



PB MOUSE LDBL CLICK 



Trigger when the cursor is in the 
pixel bar and the left mouse button 
is depressed. 

Trigger when the cursor is in the 
pixel bar and the left mouse button 
is released. 

Trigger when die cursor is in the 
pixel bar and the right mouse 
button is depressed. 

Trigger when the cursor is in the 
pixel bar and the right mouse 
button is released. 

Trigger when the cursor is in the 
pixel bar and the middle mouse 
button is depressed. 

Trigger when the cursor is in the 
pixel bar and the middle mouse 
button is released. 

Trigger when the cursor is in the 
pixel bar and there is a double click 
on the left button. 
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PB_MOUSE_RDBL_CLICK Trigger when the cursor is in the 

pixel bar and there is a double click 
on the right button. 

PB_MOUSE_MDBL_CLICK Trigger when the cursor is in the 

pixel bar and there is a double click 
on the middle button. 

PB_MOUSE_MOVEMENT Trigger when the cursor is in the 

pixel bar and its position changes. 

PB_MOUSE_LEAVE Trigger when the cursor leaves the 

pixel bar. 



jpCallback 

The function to call when the specified mouse event occurs. The function 
returns a status and has one parameter that is a pointer to the mouse event data 
structure. 

Returns 

PB_SUCCESS Function was successful 

PB ERROR An unrecoverable error occurred. 



IpParam 



i W IpParam is a pointer to the PBMouseEvent data structure. The pixel 

SO bar, the mouse event, and if applicable, the x and y locations of the 

tj mouse event are reported. 

Notes 

The issue of mouse interactions is being researched. 

Pixelbar_ClearMouseEvent 

UINT32 Pixelbar j:iearMouseEvent (UINT32 Pixelbarld, UINT32 
MouseEventld) 

Pixelbar_ClearMouseEvent() clears a previously requested set of mouse events. When the 
mouse event set is cleared, the Pixel Bar software will no longer service the set 

• Returns one of these values: 

PB SUCCESS Function was successful. 
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PB_ERROR An unrecoverable error occurred. 

Parameters 

Pixelbarld 

The id of the pixel bar. 
MouseEventld 

The Id of the mouse event set This value was returned by a previous call to 
Pixelbar_SetMouseEvent 

Notes 

The issue of mouse interactions is being researched 

Pixelbar_EnumerateMouseEvents 

(3 UINT32 Pixelbar_EnumerateMouseEvents (UINT32 Pixelbarld, UINT32 

sS *lpMouseEventWCount, UINT32 **lpMouseEventfds, UINT32 

Sj MpMouseEventldsReturned, UINT32 *IpszData, UINT32 

ru szOutputBuffer) 



Hi 



ru 

CO 



Pixelbar_EnumerateMouseEvents() returns the number of mouse events and the list of mouse 
events that have been set for the specified pixel bar. 

• Returns one of these values: 

PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

PB_BUFFER_TOO_SMALL The provided output buffer is too 

small to contain all the requested 
information. The information 
returned in the output buffer is not 
guaranteed to be coherent or valid. 
The function should be called again 
with an output buffer of the 
appropriate size. 



Parameters 

Pixelbarld 

The id of the pixel bar. 
IpMouseEventldCount 

The address of the UINT32 where the count of mouse events will be returned. 
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IpMouseEventlds 

The address of an array of UINT32 that hold the Ids of Mouse Event sets. 



IpMouseEventldsReturned 

lpMouseEventsReturned is the address of an UINT32 where the count of mouse 
event ids, which are returned in IpMouseEventlds, will be written. Unless the 
output buffer pointed to by IpMouseEventlds is too small; the value in 
IpMouseEventldsReturned is the same as in lpMouseEventldCount 



IpszData 

The address of the size of the requested data. If the value is larger than 
szOutputBuffer, then the provided buffer is too small, and the error code 
PB_BUFFER_TOO_SMALL is returned by the function. 

szOutputBuffer 

The size of the output buffer pointed to by IpMouseEventlds, in bytes. TTiis will 
allow the Pixel Bar software to refrain from overflowing the buffer. 

Notes 



None. 



X MI 

3 . 



Pixelbar_QueryMouseEvent 

UINT32 Pixelbar_QueryMouseEvent (UINT32 Pixelbarld, UINT32 
M ouseEventld, PBM ouseEventlnfo IpMouseEventlnfo, UINT32 
*lpszData, UINT32 szOutputBuffer) 

Pixelbar_QueryMouseEventO returns the mouse event state for the specified Mouse Event ID. 



• Returns one of these values: 
PB_SUCCESS 
PB_ERROR 

PB BUFFER TOO SMALL 



Function was successful. 

An unrecoverable error occurred. 

The provided output buffer is too 
small to contain all me requested 
information. The information 
returned in the output buffer is not 
guaranteed to be coherent or valid. 
The function should be called again 
with an output buffer of the 
appropriate size. 



Parameters 

Pixelbarld 



The id of the pixel bar. 
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MouseEventld 

The Id of the Mouse Event instance. 
IpMouseEventlnfo 

The address of a PBMouseEventlnfo structure that the mouse event information 
is returned in. 

IpszData 

The address of the size of foe requested data. If the value is larger than 
szOutputBuffer, then the provided buffer is too small, and the error code 
PB_BUFFER_TOO_SMALL is returned by the function. 

szOutputBuffer 

The size of the output buffer pointed to by IpMouseEventlnfo, in bytes. This 
will allow the Pixel Bar software to refrain from overflowing the buffer. 

Notes 

O 

'r> The issue of mouse interactions is being researched. 

i 

•v 

^ Pixelbar EnableMouse 

in ~ 

Cn UINT32 Pixelbar_EnableMouse (UINT32 Pixelbarld) 

PixelbarJEnableMouse enables the display of the mouse cursor icon in the specified pixel bar. 
Returns one of these values: 

PB__SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

Parameters 
Pixelbar Jd 

The id of the pixel bar. 

Notes 

None. 

Pixelbar_DisabIeMouse 

UINT32 Pixelbar JDisableMouse (UINT32 Pixelbarld) 



O 
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PixelbarJDisableMouse disables the display of the mouse cursor icon in the specified pixel 
bar. 

Returns one of these values: 

PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

Parameters 
Pixelbarjd 

The id of the pixel bar. 

Notes 

None. 

v3 

J PixelbarJJueryDisplaylnfo 

ih 

X UINT32 Pkelbar JJueryDisplaylnfo (UINT32 Displayld, PBDispIaylnfo 

[a *lpDisplayInfo, UINT32 *lpszData, UINT32 szOutputBuffer) 

f i Pixelbar_QueryDisplayInfoO queries the pixel bar software for the characteristics and current 

jf 2 state of the specified display. 



Function was successful. 

An unrecoverable error occurred. 

The provided output buffer is too 
small to contain all the requested 
information. The information 
returned in the output buffer is not 
guaranteed to be coherent or valid. 
The function should be called again 
with an output buffer of the 
appropriate size. 

Parameters 

Displayld 

The display to query. 
IpDisplaylnfo 



• Returns one of these values: 
PB_SUCCESS 
PB_ERROR 

PB BUFFER TOO SMALL 
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The address of the structure where the display info is returned. 
IpszData 

The address of the size of the requested data. If the value is larger than 
szOutputBuffer, then the provided buffer is too small, and the error code 
PBJBUFFER_TOO_SMALL is returned by the function. 

szOutputBuffer 

The size of the output buffer pointed to by IpDisplaylnfo, in bytes. This will 
allow the Pixel Bar software to refrain from overflowing the buffer. 

Notes 

The physical resolution doesn't include the scanlines used by pixel bars in 
MODE_OVERSCAN. 



Pixelbar_DisplayColor 



ru 
ru 

%.r * 



m 
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UINT32 PixelbarJMsplayCoIor (UINT32 Pixelbarld, UINT32 DestX, 
UINT32 DestY, UINT32 Xext, UINT32 Yext, UINT32 Color) 

PixelbarJDisplayColorO specifies a single color value in the current display format that the 
specified rectangle in the pixel bar is to be colored with. 



• Returns one of these values: 

PB_SUCCESS 

PB_ERROR 
Parameters 
Pixelbarld 

The pixel bar to color. 



Function was successful. 

An unrecoverable error occurred. 



DestX 



The x origin, with respect, with respect to the pixel bar origin, of the rectangle in 
the pixel bar that is to be colored. This value must be within the bounds of the 
destination pixel bar 



DestY 



The x origin, with respect, with respect to the pixel bar origin, of the rectangle in 
the pixel bar that is to be colored. This value must be within the bounds of the 
destination pixel bar 



Xext 



The width of the rectangle to be colored. The sum of DestX and Xext must be 
less than the width of the destination pixel bar. 
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Yext 

The height of the rectangle to be colored. The sum of DestY and Yext must be 
less than the height of the destination pixel bar 

Color 

A single pixel's worth of color value to color the specified rectangle within the 
pixel bar. Tlie color is in the same format as the screen. For 8 bits per pixel 
resolutions, only the least significant 8 bits have valid data; for 16 bits per pixel 
resolutions, only the least significant 16 bits have valid data; and for 24 bits per 
pixel resolutions, only the least significant 24 bits have valid data. The 
remaining bits should be 0 (zero). For 32 bits per pixel resolutions, the most 
significant 8 bits may be set to an Alpha value, which may or may not affect the 
displayed image, depending on the video device. 

For palettized mode displays (e.g. 8 bits per pixel), the pixel bar software 
currently does not provide a facility to load the color palette, and thus whatever 
color palette is loaded in the system will be used. 



Notes 



m 



The pixel bar coordinate system is the same kind as that of the display, with a 
different origin. For Windows pixel bars, the origin is at the upper left corner of 
the pixel bar, and the x values increase from left to right, and the y values 
» ^ increase from top to bottom. 

cn 

I* Pixelbar_DisplayBitmap 

In UINT32 Pixelbar_DisplayBitmap (UINT32 Pixelbarld, UINT32 SrcX, 

(0 UINT32 SrcY, UINT32 DestX, UINT32 DestY, UINT32 Xext, UINT32 

q Yext, UINT32 szBitmap, UINT32 SrcStride, VOID *lpBitmap) 



Pixelbar_DisplayBitmapO displays the specified bitmap onto the specified rectangle in the 
pixel bar. 

• Returns one of these values: 

PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

Parameters 

Pixelbarld 

The destination pixel bar. 
SrcX 
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The x origin, with respect, with respect to the source bitmap origin, of the source 
rectangle in the source bitmap. The origin is at the upper left corner of the 
bitmap. This value must be within the bounds of the source bitmap. 



SrcY 



The y origin, with respect, with respect to the source bitmap origin, of the source 
rectangle in the source bitmap. The origin is at the upper left corner of the 
bitmap. This value must be within the bounds of the source bitmap. 



DestX 



The x origin, with respect, with respect to the pixel bar origin, of the destination 
rectangle. This value must be within the bounds of the destination pixel bar. 



DestY 



The x origin, with respect, with respect to the pixel bar origin, of the destination 
rectangle. This value must be within the bounds of the destination pixel bar. 

Xext 

^ The width of the destination rectangle. The sum of SrcX and Xext must be less 

^ than the width of the source bitmap. Also the sum of DestX and Xext must be 

less than the width of the destination pixel bar. 

FU 

m Yext 



ru 

The height of the destination rectangle. The sum of SrcY and Yext must be less 
than the height of the source bitmap. Also the sum of DestY and Yext must be 
f less than the height of the destination pixel bar. 



f 53 szBitmap 



The size (in the number of bytes) of the source bitmap. 
SrcStride 

The number of bytes in each horizontal line of the source bitmap. 
IpBitmap 

The address of the source bitmap. The bitmap must be in the same screen 
format (e.g. number of bits per pixel, bits per color, etc.) as the destination 
display. 

Notes 

The pixel bar coordinate system is the same kind as that of the display, with a 
different origin. For Windows pixel bars, the origin is at the upper left comer of 
the pixel bar, and the x values increase from left to right, and the y values 
increase from top to bottom. 

For palettized mode displays (e.g. 8 bits per pixel), the pixel bar software 
currently does not provide a facility to load the color palette, and thus whatever 
color palette is loaded in the system will be used. 
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Pixelbar_SetDisplayEvent 

UINT32 PixelbarJSetDisplayEvent (UINT32 Displayld, UINT32 
DisplayEvent, UINT32 (*fpCa!lback)(PBDisplayEvent *lpParam)) 



PixelbarJSetDisplay Event provides the application with a method to be asynchronously 
notified of various xSides events. The notification is performed via function callbacks. 

• Returns one of these values: 



a 



ffi 

ru 
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PB_SUCCESS Function was successful. 

PB_ERROR An unrecoverable error occurred. 

Parameters 

Displayld 

The id of the display device. Currently, only display id 0 (zero) is supported. 
For the PB^VENTJDRIVERJEXIT event, only display id 0 is valid. 

DisplayEvent 

The display event that triggers the callback function. It may be one of the 
following: 



PB_EVENT_DRIVER_UNDEFINED 
PB_EVENT_DRIVER_ERROR 

XSD FATAL ERROR 



Not currently used, but reserved for 
future use. 

Trigger when the xSides Driver 
encounters an error condition. An 
error code is returned. The error 
codes include: 

A fatal error in the xSides Driver 
has been encountered. 



XSD_CONTROLJSfOT_FOUND 

XSD_DRIVER_HOOK_FAILED 

PB_EVENT_SCREEN_SAVER_ON 
PB_EVENT_SCREEN_SAVER_OFF 



The video driver's Control() 
function cannot be found. This is 
a fatal error for the xSides 
software running on Windows 9x. 

The attempt to hook the video 
driver for Driver Hook Overscan 
has failed. 

Trigger when screen saver starts 
running. 

Trigger when screen saver stops 
running. 
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PB EVENT DOS FULL SCREEN ON 



PB EVENT DOS FULL SCREEN OFF 



Trigger when a DOS shell goes to 
full screen mode. 

Trigger when a DOS shell ends its 
full screen mode. 



PB EVENT DD FULL SCREEN ON 



PB EVENT DP FULL SCREEN OFF 



PB EVENT MONITOR ON 



Trigger when a DirectDraw 
window goes to full screen mode. 

Trigger when a DirectDraw 
window ends its full screen mode. 

Trigger when the display monitor is 
turned on. 



PB EVENT MONITOR OFF 



Trigger when the display monitor is 
turned off, e.g. for power saver 
mode. 



v3 
M 

cn 
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PB EVENT RESOLUTION CHANGE 



PB EVENT DD FAILURE 



PB EVENT MSG MODE BEGIN 



PB EVENT MSG MODE END 



fpCattback 



Trigger when the display resolution 
is changed, and return the new 
display resolution. 

Trigger when Direct Draw 
encounters an unrecoverable error. 

Trigger when the message mode 
(aka "Blue Screen of Death") 
occurs. 

Trigger when the message mode 
(aka "Blue Screen of Death") has 
ended. 



The function to call when the specified display event occurs. The function 
returns a status and has one parameter that is a pointer to the display event data 
structure. 



Returns 



PBJSUCCESS Function was successful. 

PB ERROR An unrecoverable error occurred. 



IpParam 
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IpParam is a pointer to the PBDisplayEvent data structure. The display 
id, the display event, and if applicable, new screen resolutions are 
contained in the structure. 



Notes 

Pixelbar_ClearDisplayEvent 

UINT32 PixeIbar_CIearDisplayEvent (UINT32 Displayld, UINT32 
DisplayEvent) 

Pixelbar_ClearDisplayEvent() clears a previously requested display event When the display 
event set is cleared, the Pixel Bar software will no longer service the event 

• Returns one of these values: 

PB JSUCCESS Function was successful. 




Displayld 



Parameters 



The id of the display device. Currently, only display id 0 (zero) is supported. 
For the PB_EVENT_DRIVEREXU event, only display id 0 is valid. 



PB ERROR 



An unrecoverable error occurred. 




DisplayEvent 



The display event being cleared, which was previously specified and associated 
with a callback function by Pixelbar_SetDisplayEvent(). It may be one of the 
following; 



PB EVENT DRIVER UNDEFINED 



Not currently used, but reserved for 
future use. 



PB EVENT DRIVER ERROR 



Trigger when the xSides Driver 
encounters an error condition. An 
error code is returned The error 
codes include: 



XSD FATAL ERROR 



A fatal error in the xSides Driver 
has been encountered. 



XSD CONTROL NOT FOUND 



The video driver's ControlO 
function cannot be found. This is 
a fatal error for the xSides 
software running on Windows 9x. 



XSD DRIVER HOOK FAILED 



The attempt to hook the video 
driver for Driver Hook Overscan 
has failed. 
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PB EVENT SCREEN SAVER ON 



PB EVENT SCREEN SAVER OFF 



PB EVENT DOS FULL SCREEN ON 



Trigger when screen saver starts 
running. 

Trigger when screen saver stops 
running. 

Trigger when a DOS shell goes to 
full screen mode. 



PB EVENT DOS FULL SCREEN OFF 



Trigger when a DOS shell ends its 
full screen mode. 



PB EVENT DD FULL SCREEN ON 



PB EVENT DD FULL SCREEN OFF 



Trigger when a DirectDraw 
window goes to full screen mode. 

Trigger when a DirectDraw 
window ends its full screen mode. 



ru 
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PB EVENT MONITOR ON 



PB EVENT MONITOR OFF 



PB EVENT RESOLUTION CHANGE 



PB EVENT DD FAILURE 



PB EVENT MSG MODE BEGIN 



PB EVENT MSG MODE END 



Trigger when the display monitor is 
turned on. 

Trigger when the display monitor is 
turned off, e.g. for power saver 
mode. 

Trigger when the display resolution 
is changed, and return the new 
display resolution. 

Trigger when Direct Draw 
encounters an unrecoverable error. 

Trigger when the message mode 
(aka "Blue Screen of Death") 
occurs. 

Trigger when the message mode 
(aka "Blue Screen of Death") has 
ended. 



Notes 



Pixelbar_EnumerateDisplayEvents 



UINT32 PixelbarJEnumerateDispIayEvents (UEMT32 Displayld, UINT32 
*IpDispiayEvenfldCount,WNT32 **lpDisplayEvents, UINT32 
*lpDispIayEventsReturned, UINT32 *lpszData, UINT32 szOutputBuffer) 

Pixelbar_EnumerateDisplayEventsO returns the number of display events and the list of 
display events that have been set for the specified display device. 



28 



The Pixel Bar API 



11/27/00 12:41PM 



xSides Corporation 



Draft 1.01 



• Returns one of these values: 
PB_SUCCESS 
PB_ERROR 

PBBUFFERJTOOSMALL 



Function was successful. 

An unrecoverable error occurred. 

The provided output buffer is too 
small to contain all the requested 
information. The information 
returned in the output buffer is not 
guaranteed to be coherent or valid. 
The function should be called again 
with an output buffer of the 
appropriate size. 



Parameters 

Displayld 

Q The id of the display device. Currently, only display id 0 (zero) is supported. 



5 
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For the PB_EVENT_DRIVER_EXH event, only display id 0 is valid. 
IpDisplayEventCount 



j The address of the UINT32 where the count of current display events will be 

returned. This value is equal to or greater than the value in 
J? i IpDisplayEventsReturned. 



IpDisplayEvents 

The address of an array of UINT32 that hold the Display Events that are 
currently set for the display id. 

IpDisplayEventsReturned 

IpDisplayEventsReturned is the address of an UINT32 where the count of 
display events, which are returned in IpDisplayEvents, will be written. Unless 
the output buffer pointed to by IpDisplayEvents is too small; the value in 
IpDisplayEventsReturned is the same as in IpDisplayEventCount. 

IpszData 

The address of the size of the requested data. If the value is larger than 
szOutputBuffer, then the provided buffer is too small, and the error code 
PB_BUFFER_TOO_SMALL is returned by the function. 

szOutputBuffer 

The size of the output buffer pointed to by IpDisplayEvents, in bytes. This will 
allow the Pixel Bar software to refrain from overflowing the buffer. 

Notes 
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Pixelbar_QuerySupport 



UINT32 PixeIbar_QuerySupport (UINT32 Displayld, UINT32 
xSidesMode, UINT32 XRes, UINT32 YRes, UINT32 BitsPerPixel, 
UINT32 Edge, PBSize *lpPBSize, UINT32 *lpszData, UINT32 
szOutputBuffer) 

Pixelbar_QuerySupportO returns the maximum pixel bar size(s) for the specified xSides 
Mode, display resolution and display edge. A capability structure is returened. 



• Returns one of these values: 



PB_SUCCESS Function was successful. 

PBERROR An unrecoverable error occurred. 

Parameters 



Displayld 

a 

• % g The id of the display device. Currently, only display id 0 (zero) is supported. 

Vj For the PBEVENTDRIVERJEXIT event, only display id 0 is valid. 

ry 

^ xSidesMode 

^ The xSides mode that the pixel bar is to operate in. May be one of the 

U * following: 



s ♦ MODE_SHARE Share mode - shares the current 

H display resolution with the desktop by decreasing the desktop size. 

jU 

I U • MODEJSTEPUP Step Up mode - increases the 

IQ physical resolution of the display, but keep the desktop at the current 

q resolution and use the difference for displaying the pixel bar. 

Q 

• MODE_STEPDOWN Step Down mode -- maintains the 

physical resolution of the display, but force the desktop to the next smaller 
defined resolution and use the difference for displaying the pixel bar. 



• MODE_OVERSCAN Overscan mode - reprograms the 

video hardware to provide extra scanlines at the bottom of the screen to 
display the pixel bar. This mode currendy is valid only for pixel bars at 
the bottom or top edge of the display. 

Note: The interaction of pixel bars running in different modes is currently 
undefined. 



XRes 



The horizontal resolution of the display. 
YRes 



The vertical resolution of the display. 
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BitsPerPixel 

The number of bits per pixel. 
Edge 

Edge specifies which edge of the display surface the pixel bar will be displayed 
on. May be one or more of the following: 



PB TOP EDGE 



The top edge. 



PB_BOTTOMJEDGE The bottom edge. 



PB_RIGHT_EDGE 
PB LEFT EDGE 



The right edge. This edge is not valid if the pixel bar 
is in Overscan mode. 

The left edge. This edge is not valid if the pixel bar 
is in Overscan mode. 



IpPBSize 

y*| The address of a PBSize structure that holds the size of the maximum pixel bar 

^ size. Values of 0 in either the width or height fields indicate that the xSides 

i U Driver cannot support a pixel bar.. 

Ui 

fy IpszData 

Cm 

\± The address of the size of the requested data. If the value is larger than 

szOutputBuffer, then the provided buffer is too small, and the error code 

^ PB_BUFFER_TOO_SMALL is returned by the function. 

^ szOutputBuffer 

fy 

CO The size of the output buffer pointed to by IpPBSize, in bytes. This will allow 

£3 the Pixel Bar software to refrain from overflowing the buffer. 

u 



Notes 



Pixelbar_EnumerateFilelnformation 



UINT32 Pixelbar_EnuraerateFileInformation (UINT32 *lpTotalFileCount, 
PBFilelnfo *IpFileInfo, UINT32 *IpNumFiIesReturned, UINT32 
*lpDataSizeReturned, UINT32 *IpszData, UINT32 szOutputBuffer) 

Pixelbar EnumerateFilelnformationO returns the names and versions of the currently installed 
xSides driver files. 

• Returns one of these values: 

PB_SUCCESS Function was successful. 
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PB ERROR 



An unrecoverable error occurred. 
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Parameters 

IpTotalFileCount 

Pointer to the total number of file entries. 
IpFilelnfo 

Address of the buffer where the file information is to be placed. 
IpNumFilesReturned 

Pointer to the number of returned file entries. 

IpDataSizeReturned 

Address where the amount of data — in number of bytes - that is returned (in 
the buffer specified by lpFileinfo) is placed. 

IpszData 

Address where the total amount of data ~ in number of bytes « available for 
the file information is placed. 

szOutputBuffer 

Size of the buffer pointed to by IpFileVer. 

Notes 




The data types used in the Pixel Bar API are defined here. These definitions assume a Little 
Endian (aka Intel) byte ordering where the most significant byte has the highest address. For 
the structures depicted below, the most significant byte is on the left, and the least significant 
byte is on the right, with each line depicting 32 bits (4 bytes). 



Integer Types 

UINT8 



Unsigned 8 bit integer. 



UINT16 



Unsigned 16 bit integer. 



UINT32 



Unsigned 32 bit integer. 



UINT64 



Unsigned 64 bit integer. 



INT8 



Signed 8 bit integer. 
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Signed 16 bit integer. 
Signed 32 bit integer. 
Signed 64 bit integer. 



INT16 
INT32 
INT64 

Macros 

Return Codes: 

PB_SUCCESS 0 

PBJERROR 

PB_DISPLAY_ED_OUT_OF_BOUNDS 2 
PBJDISPLAYJTOTJMT1ALIZED 3 
PB_1NVALIDJEDGEJF0R_M0DE_0VERSCAN 4 
PB_DISPLAY_EDGE_ALREADY_HAS_PDCELBAR 
PBJPIXELBARJDJDUT_OF_BOUNDS 6 
PB_PIXELBAR_„NOT_CREATED 7 
PB INVALID EDGE FOR MODE SHARE 



8 



PB_INVALID_MODE 9 
PB_INVALIDATED_ID 10 
PB_BAD_PARA METERS 1 1 

PB_ACCVIO 

PB_DISPLAY_BUSY 13 

PBJJNSUPPORTEDJIESOLUTION 

PB_XSIDES_NOTJNSTALLED 

PB_SUCCESS_NO_RES_CHANGE 

PB_BUFFER_TOO_SMALL 

PB_INSUFFICIENT_RESOURCES 

PB_ALREADY_DONE 

PB_PIXELBAR_DEACTIVE 

PB_DISPLAY - REGION_OUT^OF_BOUNDS 

PB_VERSION_MISMATCH 

PB XSIDES SUPPORTED 



12 

14 
15 
16 

18 
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19 
20 
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xSides Modes: 

MODE_OVERSCAN 

MODEJ5HARE 

MODE_STEPUP 

MODESTEPDOWN 

MODE_AUTO 

Status Flags: 

PB STATUS ACTIVE 



0 
1 
2 
3 
4 



// Overscan if possible, otherwise Share. 



PB_STATUS_EXACT_SIZE 
PB_STATUSJNVALID 

PB_STATUS_VALID_RES 8 
PB_STATUS_MOUSE_ENABLED 

PB_STATUS_DISPLAYED 9 

Display Edges: 
bitmasks to ordinals. 

PB_BOTTOMJEDGE 0 

PB_RIGHT_EDGE 1 

PB_TOP_EDGE 2 

PB LEFT EDGE 3 

Display Edge Masks: 

PB_BOTTOM_EDGE_MASK 1 

PB_R1GHT_EDGE_MASK 2 

PBTOPEDGEMASK 4 

PB LEFT EDGE MASK 8 



1 //BitO 

2 //Bit 1 
4 



// Why arent these called *_Masks? 



16 



// What is this used for? 

// What is this? 
//What is this? 

// Change from 



Mouse Events: 

PBJrfOUSEJLBUTTONJDOWN 1 

PB_MOUSE_LBUTTON_UP 2 

PB_MOUSE_RBUTTON_DOWN 4 

PB_MOUSE_RBUTTON_UP 8 
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PB_MOUSE_MBUTTON_DO WN 1 6 

PB_MOUSE_MBUTTON_UP 32 

PB_MOUSE_LDBL_CLICK 64 

PB_MOUSE_RDBL_CLICK 128 

PB_MOUSE__MDBL_CLICK 256 

PB_MOUSE_MOVEMENT 512 

PB_MOUSE_LEAVE 1024 

Display Events: 



PB. 


.EVENT, 


DRTVER_UNDEFINED 


0 


PB. 


_EVENT 


_DRIVER_ERROR 


1 


PB_ 


EVENT 


_SCREEN_SAVER_ON 


2 


PB. 


EVENT 


SCREEN_SAVER_OFF 


3 


PB. 


EVENT. 


DOS_FULL_SCREEN_ON 


4 


PB_ 


EVENT. 


DOS_FULL_SCREEN_OFF 


5 


PB_ 


EVENT. 


DD_FULL_SCREEN_ON 


6 


PB_ 


EVENT. 


DDJFULL_SCREEN_OFF 


7 


PB_ 


EVENT 


_MONITOR_ON 


8 


PB_ 


EVENT. 


_MONITOR_OFF 


9 


PB_ 


EVENT 


RESOLUTION_CHANGE 


10 


PB_ 


EVENT 


DD_FAILURE 


11 


PB_ 


EVENT, 


_MSG_MODE_BEGIN 


12 


PB_ 


EVENT 


MSG_MODEJEND 


13 



xSides Driver Error 

XSDFATAL_ERROR 0 

XSD_CONTROL_NOT_FOUND 1 

XSD DRIVER HOOK FAILED 2 
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XSD_FILE_TYPE: 

PBJDLL 10 

PB_XSIDESJ)LL 11 

PB_XSIDESK_SYS 12 

PBXSD9XDLLDLL 13 

PB_XSIDES_VXD 14 



Structure Types 

PBConfiguration 



SI 

fU 
Cm 

ri i 

en 

u 

2 

0 

Id: 



13 
C3 



UINT 16 Version 



UINT16Si2e 



UINT32 Displayld 



UINT32 PixelBarMask 



UINT32 MaxOverscanWidth 



UINT32 MaxOverscanHeight 



U1NT32 MaxOverscanBPP 



UINT32 EdgeFlags 



Version 

The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 

Size 

The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 

Displayld 

The display to apply the configuration information, 
PixelBarMask 
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A bitmask indicating the pixel bars that will be displayed. A union of 
the pixel bar edges that will be used during the current xSides session. 

MaxOverscanWidth 

The maximum cumulative width, in pixels, of the overscan regions. A 
value of 0 indicates that overscan will not be used. 

MaxOverscanHeight 

The maximum cumulative height, in pixels, of the overscan regions. A 
value of 0 indicates that overscan will not be used. 

MaxOverscanBPP 

The maximum pixel resolution that overscan pixel bars will be 
displayed in. Can be 8, 16, 24 or 32. A value of 0 indicates that 
overscan mode will not be used 

EdgeFlags 

A bitfield indicating which of the 4 sides will have pixel bars. A union 
of 1 or more of the following: 

PB_BOTTOM_EDGE 

PB_RIGHT_EDGE 

PBJTOPJEDGE 

PB_LEFTJEDGE 



PBDispiaylnfo 



UINTl 6 Version 



UTNT16 Size 



UINT32 Displayld 



UINT32 HwRezX 



UINT32 HwRezY 



UINT32 TotalRezX 



UINT32 TotalRezY 



UINT32 DesktopRezX 



UINT32 DesktopRezY 
UTNT32 BitsPerPixel 
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UINT32 RefreshFrequency 
UINT32 InterlaceFlag 
UINT32 Stride 



Version 



The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 



Size 



The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 

Displayld 

The display that the information is being returned for. 
HwRezX 



ru 

fU HwRezY 



The number of pixels along the X axis that are being displayed by the 
video driver. This number doesn't include any overscan regions. 



m The number of pixels along the Y axis that are being displayed by the 

E video driver. This number doesn't include any overscan regions. 

M 
I* 

ru 



TotalRezX 



C3 TotalRezY 



The number of pixels along the X axis that are being displayed by the 
video hardware, including all overscans regions. 



The number of pixels along the Y axis that are being displayed by the 
video hardware, including all overscan regions. 



DesktopRezX 



The number of pixels along the X axis that are being used by the 
desktop. This excludes all regions used by active pixel bars. 



DesktopRezY 



The number of pixels along the Y axis that are being used by the 
desktop. This excludes all regions used by active pixel bars. 



BitsPerPixel 
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The current pixel resolution of the display, expressed as the number of 
bits per pixel. It is assumed that the display is a packed flat, non- 
banked frame buffer. 

RefreshFrequency 

The current refresh frequency of the display. 

InterlaceFlag 

TRUE (1) if the display is interlaced, Otherwise FALSE (0). 

Stride 

The number of bytes between adjacent scan lines in the video frame 
buffer, including the bytes in the displayed scan line. If not known, 
then it should be filled with 0 (zero). 



PBPixelbarState 



m 
en 
ru 
m 



ru 



C3 



UINT16 Version 



UINT16Size 



UINT32 Pixelbarld 



UINT32 Displayld 



UINT32 XSidesMode 



UINT32 Status 



UINT32Edge 



UINT32 OriginX 



UINT32 OriginY 



UINT32 Width 



UINT32 Height 



Version 



The structure version. This occupies the third and fourth bytes of die 
structure (bytes 2 and 3). 



Size 
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The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 

Pixelbarld 

The Id of the pixel bar. 

Displayld 

The Id of the display that the pixel bar is on. 
xSidesMode 

The mode that the pixel bar is in. May be one of the following: 





MODE_OVERSCAN 




MODE_SHARE 




MODE_STEPUP 


□ 


MODE_STEPDOWN 


\Q 

V! 


MODE_AUTO 


9\ i 
a '•=) 


Status 



m 

jpy The current status of the pixel bar. The following bits are defined and 

^ may be set to TRUE (1) or FALSE (0). 



PB STATUS ACTIVE 



PB STATUS EXACT SIZE 

fU 



The edge of the display that the pixel bar is located at. May be one of 
the following: 

OriginX 

The X origin of the pixel bar, in hardware screen coordinates. 

OriginY 

The Y origin of the pixel bar, in hardware screen coordinates. 

Width 

The current width of the pixel bar, in pixels. 

Height 

The current height of the pixel bar, in pixels. 
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CURSOR_POS 

UINT32 X_Position 
UINT32 Y_Position 



XJPosition 

The X_Position of the cursor. 
Y_Position 

The YJPosition of the cursor. 

PBMouseEvent 



UINTl 6 Version 


UTNT16Size 


UINT32 Pixelbarld 


UINT32 MouseEvent 


UINT32 ButtonState 




CURSOR_POS CursorPos 


UINT32 RepeatCount 





Version 

The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3), 

Size 

The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 

Pixelbarld 

Indicates which pixel bar the mouse event occurred in. 
MouseEvent 

Indicates the mouse event being reported. May be one of: 

• PB_MOUSE_LBUTTON_DOWN 

• PBJvIOUSEJLBUTTONUP 
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• PB^MOUSE RBUTTON DOWN 

• PB_MOUSE_RBUTTON_UP 

• PB_MOUSE_MBUTTON_DOWN 

• PB_MOUSE_MBUTTON_UP 

• PB_MOUSE_LDBL_CLICK 

• PB_MOUSE_RDBL_CLICK 

• PBJtfOUSEJvmBL_CLICK 

• PB_MOUSE_MOVEMENT 

• PB_MOUSE_LEAVE 

ButtonState 

What is this? 
CursorPos 

The position of the cursor relative to the pixel bar origin of the mouse 
movement. Valid only if the mouse event is 
PB_MOUSE_MOVEMENT. 

RepeatCount 

What is this7 



PBMouseEventlnfo 



UINT16 Version 



UINT16 Size 



UINT32 Pixelbarld 



UINT32 MouseEventld 



UINT32 MouseEvent 



UINT32 fpCallbackFunction 
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Version 



□ 



The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 

Size 

The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 

Pixelbarld 

ITie Pixel Bar that the Mouse Event set is associated with. 
MouseEventld 

The Id of the Mouse Event set. 
MouseEventld 

Indicates the mouse event being reported. May be one or more of: 



ru 
en 
ru 
cn 

U 



ru 
a 



FBMOUSB 


LBUTTONJDOWN 


PB . 


.MOUSE 


J,BUTTONUP 


PB. 


MOUSE. 


RBUTTONDOWN 


PB_ 


MOUSE 


RBUTTONUP 


PB_ 


MOUSE. 


MBUTTONDOWN 


PB_ 


MOUSE 


JvffiUTTONJJP 


PB , 


.MOUSE. 


LDBL_CLICK 


PB_ 


MOUSE. 


RDBL_CLICK 


PB_ 


.MOUSE. 


MDBL_CLICK 


PB_ 


_MOUSE_ 


MOVEMENT 


PB_ 


MOUSE. 


LEAVE 



fpCallbackFunction 



The address of the callback function associated with this Mouse Event 
set 



PBDispiayEvent 
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UTNT16 Version 



UINT16 Size 



UINT32 Displayld 



UINT32 DisplayEvcnt 



UINT32 SubCode 



PBDisplaylnfo NewDisplaylnfo | UINT32 
ErrorCode 



Version 



The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 



Size 
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The structure size, in bytes, including the version and size fields. This 
occupies die first two bytes of the structure (bytes 0 and 1). 

Displayld 

Indicates which display device the display event occurred in. 
DisplayEvent 

Indicates the display event being reported. May be one of the 
following: 

PB_EVENT_DRIVER_ERROR 
PB_EVENT_SCREEN_SAVER_ON 
PBEVENTSCREENSAVEROFF 
PB_EVENT_DOSJFTJLL_SCREEN_ON 
PB_EVENT_DOS_FULL_SCREEN_OFF 
PB_EVENT_DD_FULL_SCREEN_ON 
PB_EVENT_DD_FULL_SCREEN_OFF 
PB_EVENT_MONITOR_ON 
PB_EVENT_MONTTOR_OFF 
PB_EVENT_RESOLUTION„CHANGE 
PB_EVENT_DD_FAILURE 
PB_EVENT_MSG - _MODE_BEGIN 
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• PB_EVENT_MSG_MODEJEND 
SubCode 

Indicates a sub event code for the Display Event. The default value is 
0. 

For PB_EVENT_DRIVER_ERROR, the valid subcodes are: 

• XSD_FATAL_ERROR 

• XSD_CONTROL_NOT_FOUND 

• XSD_DRTVER_HOOK_FAILED 



NewDisplaylnfo 



p 



Data reflecting the new state of the display when the event is 
PB EVENT RESOLUTION CHANGE. 



PBPixelbarSize 



ru 

if H 

f. 

5. J. 

ru 

cs 

C3 



UINT16 Version 



UINT16 Size 



UINT32 BaseWidth 



UINT32 BaseHeight 



INT32 OriginX 



INT32 OriginY 



UINT32 Width 



UINT32 Height 



Version 



Size 



The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 



The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 



BaseWidth 
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Base Width specifies the horizontal number of pixels of the 
resolution that the pixel bar size applies to. For example, if 
the size of the pixel bar for the resolution of 640x480 is being 
specified, then the BaseWidth would be set to 640. 



BaseHeight 

BaseHeight specifies the vertical number of pixels of the 
resolution that the pixel bar size applies to. For example, if 
the size of the pixel bar for the resolution of 640x480 is being 
specified, then the BaseWidth would be set to 480. 

OriginX 



q 

H OriginY 



OriginX specifies the x position on the display surface, in 
units of pixels with respect to the Desktop Origin, where the 
origin of the pixel bar (which is the upper left corner of the 
pixel bar) is located. The pixel bar origin must be consistent 
with its screen edge parameter; otherwise an error will be 
returned. This is a signed value and may be a negative value 
(which it will be for non-zero width pixel bars on the left edge 
of the screen.) 



OriginY specifies the y position on the display surface, in 
Cn units of pixels with respect to the Desktop Origin, where the 

f U origin of the pixel bar (which is the upper left comer of the 

ffl pixel bar) is located. The pixel bar origin must be consistent 

^ with its screen edge parameter; otherwise an error will be 

9 returned. This is a signed value and may be a negative value 

(which it will be for non-zero height pixel bars on the top edge 
of the screen.) 



Width 

in 



%J Width specifies the desired width of the pixel bar, in number 

Q of pixels. It may not be larger than the total physical 

horizontal resolution of the display, which include the desktop 

and the pixel bars. 



Height 

Height specifies the desired height of the pixel bar, in number 
of pixels. It may not be larger than the total physical vertical 
resolution of the display, which include the desktop and the 
pixel bars. 



PBSize 



UINT1 6 Version 


UINT16Size 


UINT32 Width 
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UTNT32 Height 



Version 



Size 



Width 



The structure versioa This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 



The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). 



m 

Hi 

m 



CO 



PBFilelnfo 



Width specifies the desired width of the pixel bar, in number 
of pixels. It may not be larger than the physical horizontal 
resolution of the display. 



Height 



Height specifies the desired height of the pixel bar, in number 
of pixels. It may not be larger than the physical vertical 
resolution of the display. 



UINT 16 Version 



UINT16Size 



XSD_FILE_TYPE edFileType 



UINT32 szFileSpec 



UINT32 szFile Version 



UINT32 dwFileSpecIndex 



UINT32 dwFileVersionlndex 



charFileData[l] 



Version 

The structure version. This occupies the third and fourth bytes of the 
structure (bytes 2 and 3). 

Size 

The structure size, in bytes, including the version and size fields. This 
occupies the first two bytes of the structure (bytes 0 and 1). Since this 
is a variable size structure, the size field allows the a buffer of 
PBFilelnfo structures to be parsed. 
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edFileType 

Width specifies the desired width of the pixel bar, in number 
of pixels. It may not be larger than the physical horizontal 
resolution of the display. 

szFileSpec 

The number of bytes in the FileSpec, which is a null 
terminated character string, including the directory path and 
file name of the xSides driver file. The null terminator is not 
counted. 

szFileVersion 

The number of bytes in the FileVersion, which is a null 
terminated character string, including version information for 
the xSides driver file. The null terminator is not counted. 

dwFileSpecIndex 

Index into the. 

dwFile Versionlndex 

Height specifies the desired height of the pixel bar, in number 
of pixels. It may not be larger than the physical vertical 
resolution of the display. 

FileData 

A character array where the FileSpec and FileVersion 
information are stored as null terminated strings. 




CURSORJPOS 

Data Definitions 

Display Edge Masks, 

Display Edges 

Display Events 

INT16 

INT32 

INT64 

INT8 

Integer Types 

Macros 



5,46 
....36 
....38 
....38 
....39 
....36 
....36 
....37 
....36 
.... 36 
....37 



PB DISPLAY BUSY 37 

PB_DISPLAY EDGE ALREADY_HASJ>DCELBA 

R 37 

PB DISPLAYJD OUT_OF_BOUNDS 37 

PBJMSPLAY NOTJNITIALIZED 37 

PBJ>ISPLAY_REGION_OUT_OF BOUNDS 38 

PB DLL 41 

PB_ERROR 37 

PB EVENT DD_FAILURE 32,40 

PB EVENT DD FULL_SCREEN_OFF29, 31, 40, 



PB_BAD_PARAMETERS 37 

PBJ30TTOM_EDGE 8, 11, 35, 38, 42 

PB BUFFER_TOO SMALL 15, 16, 17,20,21,22, 



24, 32, 33, 35, 37 



MODE_AUTO 

MODE_OVERSCAN ... 

MODE SHARE 

MODE_STEPDOWN 

MODE_STEPUP 

Mouse Events 

PB_ACCVIO 

PB ALREADY DONE 



7, 10,38,45 

7, 9, 14, 24, 34,38,45 

7, 9, 14, 34,38,45 

7, 9, 15,34, 38,45 

7, 9, 15,34,38,45 



39 
37 
37 



PB EVENT DD FULL SCREENON29, 31,40, 50 
PB_EVENT_DOS_FULL_SCREEN_OFF28, 31, 39, 
50 



50 
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PB_EVENT_DOS_FULL SCREENON28, 31, 39, 
50 

PB_EVENT DRIVERJBRROR 28, 30, 39, 50, 51 

PB_EVENT_DRIVER_EXIT 28, 30, 33, 34 

PB_EVENT_MONITOR OFF 29,31,40,50 

PB_EVENT_MONITORlON 29, 31, 40, 50 

PB EVENT MSG MODE_BEGIN 29,40,50 

PB_EVENT_MSG_MODE END 29,40,50 

PB EVENT RESOLUTION_CHANGE29,31,32, 
40,50,51 

PB_EVENT_SCREEN SAVBRJDFF ...28, 31, 39, 50 

PBJEVENT_SCREEN_SAVER_ON 28, 31, 39, 50 

PB_rNSUFFICIENT_RESOURCES 37 

PB_INVALID_EDGE_FOR_MODE OVERSCAN37 

PB_INVALID_EDGE_FOR_MODE_SHARE 37 

PB_INVALID_MODE 37 

PB_[NVALIDATED_ID 37 

PB LEFT_EDGE 8, 1 1, 35, 38, 39, 42 

PB MOUSE LBUTTON DOWN 18,39,47,48 

PB_MOUSE_LBUTTON_UP 1 8, 39, 47, 48 

PB_MOUSE_LDBL_CLICK 19, 39, 47, 49 

PB MOUSE LEAVE 39 

PB_MOUSE MBUTTON_DOWN 18,39,47,48 

PB_MOUSElMBUTTON_UP 1 8, 39, 47, 49 

PB_MOUSE_MDBL_CLICK 19, 39, 47, 49 

PB MOUSE MOVEMENT 18, 19,39,47,48,49 

PB_MOUSE_RBUTTON_DOWN 1 8, 39, 47, 48 

PB_MOUSE_RBUTTON_UP 1 8, 39, 47, 48 

PB MOUSE_RDBL_CLICK 1 9, 39, 47, 49 

PB_PIXELBAR_DEACTIVE 37 

PB PIXELBARJD OUT OF BOUNDS 37 

PB_PIXELBAR_NOT_CREATED 37 

PB_RIGHT_EDGE 8, 11,35,38,42 

PB_STATUS_ACTWE 32, 38 

PB STATUS DISPLAYED 38 

PB_STATUS_EXACT_S1ZE 38 

PB_STATUSJNACTIVE 32 

PB_STATUS_INVALID 38 

PB_STATUS_MOUSE ENABLED 38 

PB_STATUS_VALID_RES 38 

PB SUCCESS 37 

PB SUCCESS_NO RES CHANGE 37 

PBJTOP_EDGE 8, 1 1, 35, 38, 39, 42 

PB UNSUPPORTED RESOLUTION 37 

PB_VERSION_MISMATCH 38 

PB_XSD9XDLL_DLL 41 

PB_XSIDES DLL 41 

PB_XSIDES_NOT_INSTALLED - 37 

PB_XSIDES_SUPPORTED 38 

PB XSIDES_VXD 41 

PB XS1DESK SYS 41 



PBConfigu ration 5,41 

PBDisplayEvent 5, 27, 30, 49, 51, 53, 54 

PBDisplaylnfo 2, 24, 42, 49 

PBDisplayState 5 

PBMouseEvent 5, 17, 19, 46 

PBMouseEventlnfo 5, 21, 22, 48 

PBPixelbarState 2, 16, 17, 44 

PBPixelBarState 5 

Pixdbar_Activate 3, 14 

PixeIbar_C!earDisplay Event 4, 30 

PixeIbar_CIearMouseEvent 4, 19, 20 

Pixelbar.Create 3 

Pixelbar_CreatePixelBar 9, 10 

PixelbarJDeactivate 3, 14 

PixelbarDelete 3, 13 

Pixelbar_DisplayBitmap 4, 26 

Pixelbar_DisplayColor 4, 24, 25 

Phcelbar_Enumerate 3, 15 

Pixelbar_EnumerateDisplayEvents 4, 32, 33, 35 

Pixelbar_EnumerateMouseEvents 4, 20, 21 

Pixelbarjnit 3,5 

PixelbarJVtodify 3, 11, 12 

Pixelbar^Query 3, 10, 12, 15, 16 

Pixdbar_QueryDisplayInfo 4, 23, 24 

PixeIbar_QueryMouseEveDt 4, 21 

Pixelbar"SetDlsplayEvent 4, 27, 30 

Pixelbar_SetMouseEvent 4, 17, 20, 22, 23 

PixelbarJJninit 3,6 

Return Codes 37 

Status Flags 38 

Structure Types 41 

UINT16 36 

UINT32 36 

UINT64 36 

UINT8 36 

XSD_CONTROL NOT FOUND 40 

XSD DRIVER HOOK "FAILED 40 

XSD_FATAL_ERROR 40 

XSD_FILEJTYPE 41 

xSides Driver Error 40 

xSides Modes 38 

40 
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40 
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40 

40 
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